Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# C OCI Function Server Round Trips

This appendix provides information about server round trips incurred during various OCI calls. This information can be useful to programmers when determining the most efficient way to accomplish a particular task in an application.

This appendix contains these topics:

- Overview of Server Round Trips

- Relational Function Round Trips

- LOB Function Round Trips

- Object and Cache Function Round Trips

- Describe Operation Round Trips

- Datatype Mapping and Manipulation Function Round Trips

- Any Type and Data Function Round Trips

- Other Local Functions

## Overview of Server Round Trips

This appendix provides information about server round trips incurred during various OCI calls. This information can be useful when determining the most efficient way to accomplish a particular task in an application.

## Relational Function Round Trips

The number of server round trips required by OCI relational functions are listed in Table C-1:

Table C-1 Server Round Trips for Relational Operations

Function | Number of Server Round Trips
--- | ---
`OCIBreak()` | 1
`OCIDBShutdown()` | 1
`OCIDBStartup()` | 1
`OCIEnvCreate()` | 0
`OCIEnvInit()` | 0
`OCIErrorGet()` | 0
`OCIInitialize()` | 0
`OCILdaToSvcCtx()` | 0
`OCILogoff()` | 1
`OCILogon()` | 1
`OCILogon2()` | connection pool/session pool: same as OCISessionGet(). Normal: 2 (depends on authentication and TAF situation.
`OCIPasswordChange()` | 1
`OCIPing()` | 1
`OCIReset()` | 0
`OCIServerAttach()` | 1
`OCIServerDetach()` | 1
`OCIServerVersion()` | 1
`OCISessionBegin()` | 1
`OCISessionEnd()` | 1
`OCISessionGet()` | session pool: 0 - increment of logins. connection pool: 1 to (1+ (increment * logins)). Depends on cache hit: one for the user session, optional increment for primary sessions. Normal: 1 login
`OCISessionPoolCreate()` | sessMin * logins
`OCISessionPoolDestroy()` | sessions in cache * logoffs
`OCISessionRelease()` | session pooling: 0, except when explicit session destroys flag set. Normal: 1 login
`OCISvcCtxToLda()` | 0
`OCIStmtExecute()` | 1
`OCIStmtFetch()` | 0 or 1
`OCIStmtFetch2()` | 0 in pre-fetch, otherwise 1
`OCIStmtGetPieceInfo()` | 1
`OCIStmtPrepare()` | 0
`OCIStmtSetPieceInfo()` | 0
`OCITerminate()` | 1
`OCITransCommit()` | 1
`OCITransDetach()` | 1
`OCITransForget()` | 1
`OCITransPrepare()` | 1
`OCItransRollback()` | 1
`OCITransStart()` | 1
`OCIUserCallbackGet()` | 0
`OCIUserCallbackregister()` | 0

## LOB Function Round Trips

Table C-2 lists the server round trips incurred by the `OCILob` calls.

Note: To minimize the number of round trips, you can use the data interface for LOBs. You can bind or define character data for a `CLOB` column or `RAW` data for a `BLOB` column.

See Also: "Binding LOB Data" for usage and examples for both `INSERT` and `UPDATE statements` "Defining LOB Data" for usage and examples of `SELECT` statements

For calls whose number of round trips is "0 or 1", if LOB buffering is on, and the request can be satisfied in the client, no round trips are incurred.

Table C-2 Server Round Trips for OCILob Calls

Function | Number of Server Round Trips
--- | ---
`OCILobAppend()` | 1
`OCILobArrayRead()` | 1
`OCILobArraywrite()` | 1
`OCILobAssign()` | 0
`OCILobCharSetForm()` | 0
`OCILobCharSetId()` | 0
`OCILobClose()` | 1
`OCILobCopy()` | 1
`OCILobCopy2()` | 1
`OCILobCreateTemporary()` | 1
`OCILobDisableBuffering()` | 0
`OCILobEnableBuffering()` | 0
`OCILobErase()` | 1
`OCILobErase2()` | 1
`OCILobFileClose()` | 1
`OCILobFileCloseAll()` | 1
`OCILobFileExists()` | 1
`OCILobFileGetName()` | 0
`OCILobFileIsOpen()` | 1
`OCILobFileOpen()` | 1
`OCILobFileSetName()` | 0
`OCILobFlushBuffer()` | 1 for each modified page in the buffer for this LOB
`OCILobFreeTemporary()` | 1
`OCILobGetChunkSize()` | 1
`OCILobGetLength()` | 1
`OCILobGetLength2()` | 1
`OCILobGetStorageLimit()` | 1
`OCILobIsEqual()` | 0
`OCILobIsOpen()` | 1
`OCILobIsTemporary()` | 0
`OCILobLoadFromFile()` | 1
`OCILobLoadFromFile2()` | 1
`OCILobLocatorAssign()` | 1 round trip if either the source or the destination locator refers to a temporary LOB
`OCILobLocatorIsInit()` | 0
`OCILobOpen()` | 1
`OCILobRead()` | 0 or 1
`OCILobRead2()` | 0 or 1
`OCILobTrim()` | 1
`OCILobTrim2()` | 1
`OCILobWrite()` | 0 or 1
`OCILobWrite2()` | 0 or 1
`OCILobWriteAppend()` | 0 or 1
`OCILobWriteAppend2()` | 0 or 1

## Object and Cache Function Round Trips

Table C-3 lists the number of server round trips required for the object and cache functions. These values assume the cache is in a warm state, meaning that the type descriptor objects required by the application have been loaded.

Table C-3 Server Round Trips for Object and Cache Functions

Function | Number of Server Round Trips
--- | ---
`OCIObjectNew()` | 0
`OCIObjectPin()` | 1; 0 if the desired object is already in cache
`OCIObjectUnpin()` | 0
`OCIObjectPinCountReset()` | 0
`OCIObjectLock()` | 1
`OCIObjectMarkUpdate()` | 0
`OCIObjectUnmark()` | 0
`OCIObjectUnmarkByRef()` | 0
`OCIObjectFree()` | 0
`OCIObjectMarkDelete()` | 0
`OCIObjectMarkDeleteByRef()` | 0
`OCIObjectFlush()` | 1
`OCIObjectRefresh()` | 1
`OCIObjectCopy()` | 0
`OCIObjectGetTypeRef()` | 0
`OCIObjectGetObjectRef()` | 0
`OCIObjectGetInd()` | 0
`OCIObjectExists()` | 0
`OCIObjectIsLocked()` | 0
`OCIObjectIsDirty()` | 0
`OCIObjectPinTable()` | 1
`OCIObjectArrayPin()` | 1
`OCICacheFlush()` | 1
`OCICacheRefresh()` | 1
`OCICacheUnpin()` | 0
`OCICacheFree()` | 0
`OCICacheUnmark()` | 0

## Describe Operation Round Trips

The number of server round trips required by `OCIDescribeAny()`, `OCIAttrGet()`, and `OCIParamGet()` are listed in Table C-4:

Table C-4 Server Round Trips for Describe Operations

Function | Number of Server Round Trips
--- | ---
`OCIDescribeAny()` | 1 round trip to get the `REF` of the type descriptor object
`OCIAttrGet()` | 2 round trips to describe a type if the type objects are not in the object cache 1 round trip for each collection element, or each type attribute, method, or method argument descriptor. 1 more round trip if using `OCI_ATTR_TYPE_NAME`, or `OCI_ATTR_SCHEMA_NAME` on the collection element, type attribute, or method argument. 0 if all the type objects to be described are already in the object cache following the first `OCIAttrGet()` call.
`OCIParamGet()` | 0

## Datatype Mapping and Manipulation Function Round Trips

The number of round trips for the datatype mapping and manipulation functions are listed in Table C-5. The asterisks in the table indicate that all functions with a particular prefix incur the same number of server round trips. For example, `OCINumberAdd()`, `OCINumberPower()`, and `OCINumberFromText()` all incur zero server round trips.

Table C-5 Server Round Trips for Datatype Manipulation Functions

Function | Number of Server Round Trips
--- | ---
`OCINumber*()` | 0
`OCIDate*()` | 0
`OCIString*()` | 0
`OCIRaw*()` | 0
`OCIRef*()` | 0
`OCIColl*()` | 0; 1 if the collection is not loaded in the cache
`OCITable*()` | 0; 1 if the nested table is not loaded in the cache
`OCIIter*()` | 0; 1 if the collection is not loaded in the cache

## Any Type and Data Function Round Trips

The number of server round trips required by Any Type and Data functions are listed in Table C-6. The functions not listed do not generate any round trips.

Table C-6 Server Round Trips for Any Type and Data Functions

Function | Number of Server Round Trips
--- | ---
`OCIAnyDataAttrGet()` | 0; 1 if the type information is not loaded in the cache
`OCIAnyDataAttrSet()` | 0; 1 if the type information is not loaded in the cache
`OCIAnyDataCollGetElem()` | 0; 1 if the type information is not loaded in the cache

## Other Local Functions

The functions listed in Table C-7 are local and do not require a server round trip:

Table C-7 Locally Processed Functions

Local Function Name | Notes
--- | ---
`OCIAttrGet()` | When describing an object type, this call does make one round trip to fetch the type descriptor object.
`OCIAttrSet()` |
`OCIBindByName()` |
`OCIBindByPos()` |
`OCIBindDynamic()` |
`OCIBindObject()` |
`OCIBindArrayOfStruct()` |
`OCIDefineByPos()` |
`OCIDefineDynamic()` |
`OCIDefineArrayOfStruct()` |
`OCIDefineObject()` |
`OCIDescriptorAlloc()` |
`OCIDescriptorFree()` |
`OCIEnvInit()` |
`OCIEnvCreate()` |
`OCIErrorGet()` |
`OCIHandleAlloc()` |
`OCIHandleFree()` |
`OCILdaToSvcCtx()` |
`OCISvcCtxToLda()` |
`OCIStmtGetBindInfo()` |
`OCIStmtPrepare()` |
`OCIStmtRelease()` | 0
`OCIStmtGetBindInfo()` |
`OCIStmtPrepare2()` | 0